---
title: Direct OAuth
edit-this-page-url: https://github.com/airweave-ai/airweave/blob/main/fern/docs/pages/connecting-sources/direct-oauth.mdx
subtitle: Connect sources using browser OAuth flow with URL-based connections or BYOC (Bring Your Own Credentials).
slug: direct-oauth
---

## Overview

Direct OAuth allows you to create source connections using the standard OAuth 2.0 browser flow. This method provides a seamless user experience where users authenticate directly through their service provider's consent screen, without needing to manage tokens manually.

Airweave supports two main approaches for Direct OAuth:

1. **URL-based OAuth**: Users authenticate through Airweave's hosted OAuth flow
2. **BYOC (Bring Your Own Credentials)**: Use your own OAuth application credentials

## Supported Connectors

Direct OAuth is supported by most Airweave connectors. Some connectors require you to provide your own OAuth application credentials (BYOC), while others can use Airweave's hosted OAuth flow.

**Connectors requiring BYOC:**
- Dropbox, Gmail, Google Calendar, Google Drive

**Connectors using Direct Authentication only:**
- Bitbucket, GitHub, PostgreSQL, Stripe, CTTI

<Note>
Most connectors also support authentication through external providers like Composio and Pipedream.
</Note>

## URL-based OAuth Flow

The URL-based OAuth flow is the simplest way to connect sources. Users are redirected to Airweave's hosted OAuth flow, which handles the entire authentication process.

<video
      src="./direct_oauth_notion.mp4"
      controls
      loop
      autoplay
      muted
      playsinline
      style={{ aspectRatio: '16 / 9', width: '100%' }}
    >
      Your browser does not support the video tag.
    </video>

### How it works

1. **Initiate Connection**: Create a source connection using the URL-based authentication method
2. **User Consent**: Users are redirected to the service provider's consent screen
3. **Token Exchange**: Airweave exchanges the authorization code for access and refresh tokens
4. **Data Sync**: The connection is established and data synchronization begins

### Creating a URL-based OAuth connection

<CodeBlocks>
```Python title="Python"
from airweave import AirweaveSDK
from airweave.types import OAuthBrowserAuthentication

airweave = AirweaveSDK(api_key="YOUR_API_KEY", base_url="https://api.airweave.ai")

# Create source connection - returns pending connection with auth_url
source_connection = airweave.source_connections.create(
    name="Notion connection",
    short_name="notion",
    readable_collection_id="my-collection-id",
    authentication=OAuthBrowserAuthentication(
        redirect_uri="https://your-app.com/callback"
    ),
    sync_immediately=False  # OAuth browser flows cannot sync immediately
)

# Connection is now in pending state - redirect user to auth_url
print(f"Redirect user to: {source_connection.auth.auth_url}")
print(f"Connection status: {source_connection.status}")  # "pending"
print(f"Authenticated: {source_connection.auth.authenticated}")  # False
```

```javascript title="Node.js"
import { AirweaveSDKClient } from "@airweave/sdk";

const airweave = new AirweaveSDKClient({apiKey: "YOUR_API_KEY", baseUrl: "https://api.airweave.ai"});

// Create source connection - returns pending connection with auth_url
const sourceConnection = await airweave.sourceConnections.create({
    name: "Notion connection",
    shortName: "notion",
    readableCollectionId: "my-collection-id",
    authentication: {
        redirect_uri: "https://your-app.com/callback"
    },
    syncImmediately: false  // OAuth browser flows cannot sync immediately
});

// Connection is now in pending state - redirect user to auth_url
console.log(`Redirect user to: ${sourceConnection.auth.auth_url}`);
console.log(`Connection status: ${sourceConnection.status}`);  // "pending"
console.log(`Authenticated: ${sourceConnection.auth.authenticated}`);  // false
```

```bash title="cURL"
curl -X POST https://api.airweave.ai/source-connections \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Notion connection",
  "short_name": "notion",
  "readable_collection_id": "my-collection-id",
  "authentication": {
    "redirect_uri": "https://your-app.com/callback"
  },
  "sync_immediately": false
}'

# Response includes:
# {
#   "id": "connection-id",
#   "status": "pending",
#   "auth": {
#     "authenticated": false,
#     "auth_url": "https://api.airweave.ai/oauth/proxy/...",
#     "auth_url_expires": "2024-01-01T12:00:00Z"
#   }
# }
```
</CodeBlocks>

### Handling the OAuth callback

When using URL-based OAuth, you'll receive an authorization URL that you need to redirect users to. After they complete the OAuth flow, they'll be redirected back to your specified callback URL with the necessary parameters.

<Note>
**Important**: OAuth browser flows (both standard and BYOC) cannot use `sync_immediately=true`. The sync will automatically start after the user completes the OAuth authentication flow. Setting `sync_immediately=true` will result in a validation error.
</Note>

### Redirect URI basics

The `redirect_uri` is the URL where the user is sent after granting consent with the provider. It must exactly match an allowed redirect/callback URL configured for the OAuth app. Use it when you want users to return to your application after authentication (typical for hosted OAuth). For BYOC, configure the provider to allow Airweave's callback (`https://api.airweave.ai/oauth/callback`) and optionally set `redirect_uri` so Airweave can forward the user back to your app after the token exchange.

## BYOC (Bring Your Own Credentials)

BYOC allows you to use your own OAuth application credentials instead of Airweave's hosted OAuth flow. This gives you more control over the authentication process and branding.

### Benefits of BYOC

- **Custom Branding**: Use your own OAuth application with your branding
- **Enhanced Security**: Control your own OAuth application settings
- **Compliance**: Meet specific compliance requirements for your organization
- **Rate Limits**: Use your own rate limits instead of shared ones

### Setting up BYOC

To use BYOC, you'll need to:

1. **Create OAuth Application**: Set up an OAuth application with the service provider
2. **Configure Redirect URI**: Add Airweave's callback URL to your OAuth application
3. **Provide Credentials**: Use your client ID and client secret in the connection

### How BYOC Detection Works

BYOC (Bring Your Own Credentials) is automatically detected when you provide both `client_id` and `client_secret` in the `OAuthBrowserAuthentication` object. If you provide only one of these fields, the API will return a validation error.

**BYOC Detection Logic:**
- ✅ Both `client_id` AND `client_secret` provided → BYOC mode
- ✅ Neither `client_id` nor `client_secret` provided → Standard OAuth browser flow
- ❌ Only `client_id` OR only `client_secret` provided → Validation error

### Creating a BYOC connection

<CodeBlocks>
```Python title="Python"
from airweave import AirweaveSDK
from airweave.types import OAuthBrowserAuthentication

airweave = AirweaveSDK(api_key="YOUR_API_KEY", base_url="https://api.airweave.ai")

source_connection = airweave.source_connections.create(
    name="Notion connection (BYOC)",
    short_name="notion",
    readable_collection_id="my-collection-id",
    authentication=OAuthBrowserAuthentication(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
        redirect_uri="https://your-app.com/callback"
    ),
    sync_immediately=False  # BYOC flows cannot sync immediately
)
```

```javascript title="Node.js"
import { AirweaveSDKClient } from "@airweave/sdk";

const airweave = new AirweaveSDKClient({apiKey: "YOUR_API_KEY", baseUrl: "https://api.airweave.ai"});

const sourceConnection = await airweave.sourceConnections.create({
    name: "Notion connection (BYOC)",
    shortName: "notion",
    readableCollectionId: "my-collection-id",
    authentication: {
        client_id: "YOUR_CLIENT_ID",
        client_secret: "YOUR_CLIENT_SECRET",
        redirect_uri: "https://your-app.com/callback"
    },
    syncImmediately: false  // BYOC flows cannot sync immediately
});
```

```bash title="cURL"
curl -X POST https://api.airweave.ai/source-connections \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Notion connection (BYOC)",
  "short_name": "notion",
  "readable_collection_id": "my-collection-id",
  "authentication": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://your-app.com/callback"
  },
  "sync_immediately": false
}'
```
</CodeBlocks>

## OAuth Application Setup

### Required Redirect URIs

When setting up your OAuth application for BYOC, you'll need to add Airweave's callback URL as an allowed redirect URI:

```
https://api.airweave.ai/oauth/callback
```

### Required Scopes

Each connector requires specific OAuth scopes to function properly. Check the individual connector documentation for the required scopes.

### Example: GitHub OAuth Application Setup

1. Go to GitHub Settings → Developer settings → OAuth Apps
2. Click "New OAuth App"
3. Fill in the application details:
   - **Application name**: Your application name
   - **Homepage URL**: Your application URL
   - **Authorization callback URL**: `https://api.airweave.ai/oauth/callback`
4. Note down the Client ID and Client Secret for use in your BYOC connection

### Getting Help

If you encounter issues not covered in this documentation, please reach out to us at **hello@airweave.ai** or check our [API Reference](/api-reference) for more detailed information about the OAuth endpoints.
